3D Graphics Programming with QuickDraw 3D 1.5.4

Managing Lights

QuickDraw 3D provides a number of general routines for managing lights of any kind.

Q3Light_GetType

You can use the Q3Light_GetType function to get the type of a light object.



 
TQ3ObjectType Q3Light_GetType (TQ3LightObject light);

light: A light object.

DESCRIPTION

The Q3Light_GetType function returns, as its function result, the type of the light object specified by the light parameter. The types of light objects currently supported by QuickDraw 3D are defined by these constants:



 
kQ3LightTypeAmbient

kQ3LightTypeDirectional

kQ3LightTypePoint

kQ3LightTypeSpot

If the specified light object is invalid or is not one of these types, Q3Light_GetType returns the value kQ3ObjectTypeInvalid .

Q3Light_GetState

You can use the Q3Light_GetState function to get the current state of a light.



 
TQ3Status Q3Light_GetState (

                     TQ3LightObject light, 

                     TQ3Boolean *isOn);

light: A light object.
isOn: On exit, the current state of the light specified by the light parameter.

DESCRIPTION

The Q3Light_GetState function returns, in the isOn parameter, a Boolean value that indicates whether the light specified by the light parameter is active (kQ3True ) or inactive (kQ3False ).

Q3Light_SetState

You can use the Q3Light_SetState function to set the state of a light.



 
TQ3Status Q3Light_SetState (

                     TQ3LightObject light, 

                     TQ3Boolean isOn);

light: A light object.
isOn: The desired state of the specified light.

DESCRIPTION

The Q3Light_SetState function sets the state of the light specified by the light parameter to the value specified by the isOn parameter. If isOn is set to kQ3True , the light is made active; if isOn is set to kQ3False , the light is made inactive.

Q3Light_GetBrightness

You can use the Q3Light_GetBrightness function to get the current brightness of a light.



 
TQ3Status Q3Light_GetBrightness (

                     TQ3LightObject light, 

                     float *brightness);

light: A light object.
brightness: On exit, the current brightness of the specified light.

DESCRIPTION

The Q3Light_GetBrightness function returns, in the brightness parameter, a value that indicates the current brightness of the light specified by the light parameter. The value should be between 0.0 and 1.0, inclusive. Some renderers may allow you to specify overbright lights (where the value in this field is greater than 1.0) or lights with negative brightness (where the value in this field is less than 0.0). If you have a light that has non-linear distance attenuation, you may need brightness values above 1.0 for realistic modeling (imagine the sun). The effects produced by out-of-range brightness values are renderer-specific.

Q3Light_SetBrightness

You can use the Q3Light_SetBrightness function to set the brightness of a light.



 
TQ3Status Q3Light_SetBrightness (

                     TQ3LightObject light, 

                     float brightness);

light: A light object.
brightness: The desired brightness of the specified light.

DESCRIPTION

The Q3Light_SetBrightness function sets the brightness of the light specified by the light parameter to the value specified by the brightness parameter. The value should be between 0.0 and 1.0, inclusive. Some renderers may allow you to specify overbright lights (where the value in this field is greater than 1.0) or lights with negative brightness (where the value in this field is less than 0.0). If you have a light that has non-linear distance attenuation, you may need brightness values above 1.0 for realistic modeling (imagine the sun). The effects produced by out-of-range brightness values are renderer-specific.

Q3Light_GetColor

You can use the Q3Light_GetColor function to get the current color of a light.



 
TQ3Status Q3Light_GetColor (

                     TQ3LightObject light, 

                     TQ3ColorRGB *color);

light: A light object.
color: On exit, a pointer to a TQ3ColorRGB structure specifying the current color of the specified light.

DESCRIPTION

The Q3Light_GetColor function returns, in the color parameter, the current color of the light specified by the light parameter.

Q3Light_SetColor

You can use the Q3Light_SetColor function to set the color of a light.



 
TQ3Status Q3Light_SetColor (

                     TQ3LightObject light, 

                     const TQ3ColorRGB *color);

light: A light object.
color: A pointer to a TQ3ColorRGB structure specifying the desired color of the specified light.

DESCRIPTION

The Q3Light_SetColor function sets the color of the light specified by the light parameter to the value specified by the color parameter.

Q3Light_GetData

You can use the Q3Light_GetData function to get the basic data associated with a light.



 
TQ3Status Q3Light_GetData (

                     TQ3LightObject light, 

                     TQ3LightData *lightData);

light: A light object.
lightData: On exit, a pointer to a light data structure.

DESCRIPTION

The Q3Light_GetData function returns, through the lightData parameter, basic information about the light specified by the light parameter. See "Light Data Structure" for a description of a light data structure.

Q3Light_SetData

You can use the Q3Light_SetData function to set the basic data associated with a light.



 
TQ3Status Q3Light_SetData (

                     TQ3LightObject light, 

                     const TQ3LightData *lightData);

light: A light object.
lightData: A pointer to a light data structure.

DESCRIPTION

The Q3Light_SetData function sets the data associated with the light specified by the light parameter to the data specified by the lightData parameter.